<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Lrexlib 2.2 Reference Manual</title>
<link rel="stylesheet" href="lrexlib.css" type="text/css" />
</head>
<body>
<div class="document" id="lrexlib-2-2-reference-manual">
<h1 class="title">Lrexlib 2.2 Reference Manual</h1>

<div class="contents topic">
<p class="topic-title first"><a id="table-of-contents" name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#introduction" id="id1" name="id1">Introduction</a></li>
<li><a class="reference" href="#notes" id="id2" name="id2">Notes</a></li>
<li><a class="reference" href="#common-pcre-and-posix-functions-and-methods" id="id3" name="id3">Common (PCRE and POSIX) functions and methods</a><ul>
<li><a class="reference" href="#match" id="id4" name="id4">match</a></li>
<li><a class="reference" href="#find" id="id5" name="id5">find</a></li>
<li><a class="reference" href="#gmatch" id="id6" name="id6">gmatch</a></li>
<li><a class="reference" href="#gsub" id="id7" name="id7">gsub</a></li>
<li><a class="reference" href="#split" id="id8" name="id8">split</a></li>
<li><a class="reference" href="#flags" id="id9" name="id9">flags</a></li>
<li><a class="reference" href="#new" id="id10" name="id10">new</a></li>
<li><a class="reference" href="#tfind" id="id11" name="id11">tfind</a></li>
<li><a class="reference" href="#exec" id="id12" name="id12">exec</a></li>
</ul>
</li>
<li><a class="reference" href="#pcre-only-functions-and-methods" id="id13" name="id13">PCRE-only functions and methods</a><ul>
<li><a class="reference" href="#dfa-exec" id="id14" name="id14">dfa_exec</a></li>
<li><a class="reference" href="#maketables" id="id15" name="id15">maketables</a></li>
<li><a class="reference" href="#config" id="id16" name="id16">config</a></li>
<li><a class="reference" href="#version" id="id17" name="id17">version</a></li>
</ul>
</li>
<li><a class="reference" href="#other-functions" id="id18" name="id18">Other functions</a><ul>
<li><a class="reference" href="#plainfind" id="id19" name="id19">plainfind</a></li>
</ul>
</li>
<li><a class="reference" href="#incompatibilities-with-the-previous-versions" id="id20" name="id20">Incompatibilities with the Previous Versions</a></li>
</ul>
</div>
<hr class="docutils" />
<div class="section">
<h2><a class="toc-backref" href="#id1" id="introduction" name="introduction">Introduction</a></h2>
<p><strong>Lrexlib</strong> provides bindings of the two principal regular expression library
interfaces (<a class="reference" href="http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html">POSIX</a> and <a class="reference" href="http://www.pcre.org/pcre.txt">PCRE</a>) to <a class="reference" href="http://www.lua.org">Lua</a> 5.1.</p>
<p><strong>Lrexlib</strong> builds into shared libraries called by default <em>rex_posix.so</em> and
<em>rex_pcre.so</em>, which can be used with <em>require</em>.</p>
<p><strong>Lrexlib</strong> is copyright Reuben Thomas 2000-2007 and copyright Shmuel Zeigerman
2004-2007, and is released under the MIT license.</p>
</div>
<hr class="docutils" />
<div class="section">
<h2><a class="toc-backref" href="#id2" id="notes" name="notes">Notes</a></h2>
<ol class="arabic">
<li><p class="first">Most functions and methods in Lrexlib have mandatory and optional arguments.
There are no dependencies between arguments in Lrexlib's functions and
methods. Any optional argument can be supplied as <tt class="docutils literal"><span class="pre">nil</span></tt> (or omitted if it
is trailing one), the library will then use the default value for that
argument.</p>
</li>
<li><p class="first">This document uses the following syntax for optional arguments: they are
bracketed separately, and commas are left outside brackets, e.g.:</p>
<pre class="literal-block">
MyFunc (arg1, arg2, [arg3], [arg4])
</pre>
</li>
<li><p class="first">Throughout this document, the identifier <em>rex</em> is used in place of either
<em>rex_posix</em> or <em>rex_pcre</em>, that are the default namespaces for the
corresponding libraries.</p>
</li>
<li><p class="first">All functions receiving a regular expression pattern as an argument will
generate an error if that pattern is found invalid by the used <a class="reference" href="http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html">POSIX</a> / <a class="reference" href="http://www.pcre.org/pcre.txt">PCRE</a>
library.</p>
</li>
</ol>
<ol class="arabic" id="cf" start="5">
<li><p class="first">The default value for <em>compilation flags</em> (<em>cf</em>) that Lrexlib uses when
the parameter is not supplied or <tt class="docutils literal"><span class="pre">nil</span></tt>, is:</p>
<blockquote>
<ul class="simple">
<li>0 for PCRE</li>
<li>REG_EXTENDED for POSIX regex library</li>
</ul>
</blockquote>
<p>For PCRE, <em>cf</em> may also be supplied as a string, whose characters stand for
PCRE compilation flags. Combinations of the following characters (case
sensitive) are supported:</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="45%" />
<col width="55%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head"><p class="first last"><strong>Character</strong></p>
</th>
<th class="head"><p class="first last"><strong>PCRE flag</strong></p>
</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><p class="first last"><strong>i</strong></p>
</td>
<td><p class="first last">PCRE_CASELESS</p>
</td>
</tr>
<tr><td><p class="first last"><strong>m</strong></p>
</td>
<td><p class="first last">PCRE_MULTILINE</p>
</td>
</tr>
<tr><td><p class="first last"><strong>s</strong></p>
</td>
<td><p class="first last">PCRE_DOTALL</p>
</td>
</tr>
<tr><td><p class="first last"><strong>x</strong></p>
</td>
<td><p class="first last">PCRE_EXTENDED</p>
</td>
</tr>
<tr><td><p class="first last"><strong>U</strong></p>
</td>
<td><p class="first last">PCRE_UNGREEDY</p>
</td>
</tr>
<tr><td><p class="first last"><strong>X</strong></p>
</td>
<td><p class="first last">PCRE_EXTRA</p>
</td>
</tr>
</tbody>
</table>
</blockquote>
</li>
</ol>
<ol class="arabic" id="ef" start="6">
<li><p class="first">The default value for <em>execution flags</em> (<em>ef</em>) that Lrexlib uses when
the parameter is not supplied or <tt class="docutils literal"><span class="pre">nil</span></tt>, is:</p>
<blockquote>
<ul class="simple">
<li>0 for PCRE</li>
<li>0 for standard POSIX regex library</li>
<li>REG_STARTEND for those POSIX regex libraries that support it,
e.g. Spencer's.</li>
</ul>
</blockquote>
</li>
</ol>
<ol class="arabic simple" id="locale" start="7">
<li>Parameter <em>locale</em> (<em>lo</em>) can be either a string (e.g., &quot;French_France.1252&quot;),
or a userdata obtained from a call to <a class="reference" href="#maketables">maketables</a>. The default value, used
when the parameter is not supplied or <tt class="docutils literal"><span class="pre">nil</span></tt>, is the built-in PCRE set of
character tables.</li>
</ol>
</div>
<hr class="docutils" />
<div class="section">
<h2><a class="toc-backref" href="#id3" id="common-pcre-and-posix-functions-and-methods" name="common-pcre-and-posix-functions-and-methods">Common (PCRE and POSIX) functions and methods</a></h2>
<div class="section">
<h3><a class="toc-backref" href="#id4" id="match" name="match">match</a></h3>
<p><tt class="funcdef docutils literal"><span class="pre">rex.match</span> <span class="pre">(subj,</span> <span class="pre">patt,</span> <span class="pre">[init],</span> <span class="pre">[cf],</span> <span class="pre">[ef],</span> <span class="pre">[lo])</span></tt></p>
<p>The function searches for the first match of the regexp <em>patt</em> in the string
<em>subj</em>, starting from offset <em>init</em>, subject to flags <em>cf</em> and <em>ef</em>.</p>
<p>PCRE: A locale <em>lo</em> may be specified.</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="15%" />
<col width="51%" />
<col width="13%" />
<col width="21%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Parameter</th>
<th class="head">Description</th>
<th class="head">Type</th>
<th class="head">Default Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>subj</td>
<td>subject</td>
<td>string</td>
<td>n/a</td>
</tr>
<tr><td>patt</td>
<td>regular expression pattern</td>
<td>string</td>
<td>n/a</td>
</tr>
<tr><td>[init]</td>
<td>start offset in the subject
(can be negative)</td>
<td>number</td>
<td>1</td>
</tr>
<tr><td>[cf]</td>
<td>compilation flags (bitwise OR)</td>
<td>number</td>
<td><a class="reference" href="#cf">cf</a></td>
</tr>
<tr><td>[ef]</td>
<td>execution flags (bitwise OR)</td>
<td>number</td>
<td><a class="reference" href="#ef">ef</a></td>
</tr>
<tr><td>[lo]</td>
<td>[PCRE] locale</td>
<td>string
or
userdata</td>
<td><a class="reference" href="#locale">locale</a></td>
</tr>
</tbody>
</table>
</blockquote>
<dl class="docutils">
<dt><strong>Returns on success:</strong></dt>
<dd><ol class="first last arabic simple">
<li>All substring matches (&quot;captures&quot;), in the order they appear in the
pattern. <tt class="docutils literal"><span class="pre">false</span></tt> is returned for sub-patterns that did not participate in
the match. If the pattern specified no captures then the whole matched
substring is returned.</li>
</ol>
</dd>
<dt><strong>Returns on failure:</strong></dt>
<dd><ol class="first last arabic simple">
<li><tt class="docutils literal"><span class="pre">nil</span></tt></li>
</ol>
</dd>
</dl>
</div>
<hr class="docutils" />
<div class="section">
<h3><a class="toc-backref" href="#id5" id="find" name="find">find</a></h3>
<p><tt class="funcdef docutils literal"><span class="pre">rex.find</span> <span class="pre">(subj,</span> <span class="pre">patt,</span> <span class="pre">[init],</span> <span class="pre">[cf],</span> <span class="pre">[ef],</span> <span class="pre">[lo])</span></tt></p>
<p>The function searches for the first match of the regexp <em>patt</em> in the string
<em>subj</em>, starting from offset <em>init</em>, subject to flags <em>cf</em> and <em>ef</em>.</p>
<p>PCRE: A locale <em>lo</em> may be specified.</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="15%" />
<col width="51%" />
<col width="13%" />
<col width="21%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Parameter</th>
<th class="head">Description</th>
<th class="head">Type</th>
<th class="head">Default Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>subj</td>
<td>subject</td>
<td>string</td>
<td>n/a</td>
</tr>
<tr><td>patt</td>
<td>regular expression pattern</td>
<td>string</td>
<td>n/a</td>
</tr>
<tr><td>[init]</td>
<td>start offset in the subject
(can be negative)</td>
<td>number</td>
<td>1</td>
</tr>
<tr><td>[cf]</td>
<td>compilation flags (bitwise OR)</td>
<td>number</td>
<td><a class="reference" href="#cf">cf</a></td>
</tr>
<tr><td>[ef]</td>
<td>execution flags (bitwise OR)</td>
<td>number</td>
<td><a class="reference" href="#ef">ef</a></td>
</tr>
<tr><td>[lo]</td>
<td>[PCRE] locale</td>
<td>string
or
userdata</td>
<td><a class="reference" href="#locale">locale</a></td>
</tr>
</tbody>
</table>
</blockquote>
<dl class="docutils">
<dt><strong>Returns on success:</strong></dt>
<dd><ol class="first last arabic simple">
<li>The start point of the match (a number).</li>
<li>The end point of the match (a number).</li>
<li>All substring matches (&quot;captures&quot;), in the order they appear in the
pattern. <tt class="docutils literal"><span class="pre">false</span></tt> is returned for sub-patterns that did not participate in
the match.</li>
</ol>
</dd>
<dt><strong>Returns on failure:</strong></dt>
<dd><ol class="first last arabic simple">
<li><tt class="docutils literal"><span class="pre">nil</span></tt></li>
</ol>
</dd>
</dl>
</div>
<hr class="docutils" />
<div class="section">
<h3><a class="toc-backref" href="#id6" id="gmatch" name="gmatch">gmatch</a></h3>
<p><tt class="funcdef docutils literal"><span class="pre">rex.gmatch</span> <span class="pre">(subj,</span> <span class="pre">patt,</span> <span class="pre">[cf],</span> <span class="pre">[ef],</span> <span class="pre">[lo])</span></tt></p>
<p>The function is intended for use in the <em>generic for</em> Lua construct.
It returns an iterator for repeated matching of the pattern <em>patt</em> in
the string <em>subj</em>, subject to flags <em>cf</em> and <em>ef</em>.</p>
<p>PCRE: A locale <em>lo</em> may be specified.</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="15%" />
<col width="51%" />
<col width="13%" />
<col width="21%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Parameter</th>
<th class="head">Description</th>
<th class="head">Type</th>
<th class="head">Default Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>subj</td>
<td>subject</td>
<td>string</td>
<td>n/a</td>
</tr>
<tr><td>patt</td>
<td>regular expression pattern</td>
<td>string</td>
<td>n/a</td>
</tr>
<tr><td>[cf]</td>
<td>compilation flags (bitwise OR)</td>
<td>number</td>
<td><a class="reference" href="#cf">cf</a></td>
</tr>
<tr><td>[ef]</td>
<td>execution flags (bitwise OR)</td>
<td>number</td>
<td><a class="reference" href="#ef">ef</a></td>
</tr>
<tr><td>[lo]</td>
<td>[PCRE] locale</td>
<td>string
or
userdata</td>
<td><a class="reference" href="#locale">locale</a></td>
</tr>
</tbody>
</table>
</blockquote>
<p>The iterator function is called by Lua. On every iteration (that is, on every
match), it returns all captures in the order they appear in the pattern (or the
entire match if the pattern specified no captures). The iteration will continue
till the subject fails to match.</p>
</div>
<hr class="docutils" />
<div class="section">
<h3><a class="toc-backref" href="#id7" id="gsub" name="gsub">gsub</a></h3>
<p><tt class="funcdef docutils literal"><span class="pre">rex.gsub</span> <span class="pre">(subj,</span> <span class="pre">patt,</span> <span class="pre">repl,</span> <span class="pre">[n],</span> <span class="pre">[cf],</span> <span class="pre">[ef],</span> <span class="pre">[lo])</span></tt></p>
<p>This function searches for all matches of the pattern <em>patt</em> in the string
<em>subj</em> and replaces them according to the parameters <em>repl</em> and <em>n</em> (see details
below).</p>
<p>PCRE: A locale <em>lo</em> may be specified.</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="11%" />
<col width="43%" />
<col width="30%" />
<col width="16%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Parameter</th>
<th class="head">Description</th>
<th class="head">Type</th>
<th class="head">Default Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>subj</td>
<td>subject</td>
<td>string</td>
<td>n/a</td>
</tr>
<tr><td>patt</td>
<td>regular expression pattern</td>
<td>string</td>
<td>n/a</td>
</tr>
<tr><td>repl</td>
<td>substitution source</td>
<td>string, function or table</td>
<td>n/a</td>
</tr>
<tr><td>[n]</td>
<td>maximum number of matches to search
for, or control function, or nil</td>
<td>number or function</td>
<td><tt class="docutils literal"><span class="pre">nil</span></tt></td>
</tr>
<tr><td>[cf]</td>
<td>compilation flags (bitwise OR)</td>
<td>number</td>
<td><a class="reference" href="#cf">cf</a></td>
</tr>
<tr><td>[ef]</td>
<td>execution flags (bitwise OR)</td>
<td>number</td>
<td><a class="reference" href="#ef">ef</a></td>
</tr>
<tr><td>[lo]</td>
<td>[PCRE] locale</td>
<td>string or userdata</td>
<td><a class="reference" href="#locale">locale</a></td>
</tr>
</tbody>
</table>
</blockquote>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd><ol class="first last arabic simple">
<li>The subject string with the substitutions made.</li>
<li>Number of matches found.</li>
<li>Number of substitutions made.</li>
</ol>
</dd>
<dt><strong>Details:</strong></dt>
<dd><p class="first">The parameter <em>repl</em> can be either a string, a function or a table.
On each match made, it is converted into a value <em>repl_out</em> that may be used
for the replacement.</p>
<p><em>repl_out</em> is generated differently depending on the type of <em>repl</em>:</p>
<ol class="arabic simple">
<li>If <em>repl</em> is a <em>string</em> then it is treated as a template for substitution,
where the %X occurences in <em>repl</em> are handled in a special way, depending
on the value of the character X:</li>
</ol>
<blockquote>
<ul class="simple">
<li>if X represents a digit, then each %X occurence is substituted by the
value of the X-th submatch (capture), with the following cases handled
specially:<ul>
<li>each %0 is substituted by the entire match</li>
<li>if the pattern contains no captures, then each %1 is substituted by the
entire match</li>
<li>any other %X where X is greater than the number of captures in the
pattern will generate an error (&quot;invalid capture index&quot;)</li>
<li>if the pattern does contain a capture with number X but that capture
didn't participate in the match, then %X is substituted by an empty
string</li>
</ul>
</li>
<li>if X is any non-digit character then %X is substituted by X</li>
</ul>
<p>All parts of <em>repl</em> other than %X are copied to <em>repl_out</em> verbatim.</p>
</blockquote>
<ol class="arabic simple" start="2">
<li>If <em>repl</em> is a <em>function</em> then it is called on each match with the
submatches passed as parameters (if there are no submatches then the entire
match is passed as the only parameter). <em>repl_out</em> is the return value of
the <em>repl</em> call, and is interpreted as follows:</li>
</ol>
<blockquote>
<ul class="simple">
<li>if it is a string or a number (coerced to a string), then the replacement
value is that string;</li>
<li>if it is a <tt class="docutils literal"><span class="pre">nil</span></tt> or a <tt class="docutils literal"><span class="pre">false</span></tt>, then no replacement is to be done;</li>
</ul>
</blockquote>
<ol class="arabic simple" start="3">
<li>If <em>repl</em> is a table then <em>repl_out</em> is <em>repl</em> [m1], where m1 is the first
submatch (or the entire match if there are no submatches), following the
same rules as for the return value of <em>repl</em> call, described in the above
paragraph.</li>
</ol>
<p>Note: Under some circumstances, the value of <em>repl_out</em> may be ignored; see
<a class="reference" href="#below">below</a>.</p>
<p>gsub behaves differently depending on the type of <em>n</em>:</p>
<ol class="last arabic simple">
<li>If <em>n</em> is a <em>number</em> then it is treated as the maximum number of matches
to search for (an omitted or <tt class="docutils literal"><span class="pre">nil</span></tt> value means an unlimited number of
matches). On each match, the replacement value is the <em>repl_out</em> string
(see above).</li>
</ol>
</dd>
</dl>
<blockquote id="below">
<ol class="arabic" start="2">
<li><p class="first">If <em>n</em> is a function, then it is called on each match, after <em>repl_out</em> is
produced (so if <em>repl</em> is a function, it will be called prior to the <em>n</em>
call).</p>
<p><em>n</em> receives 3 arguments and returns 2 values. Its arguments are:</p>
<blockquote>
<ol class="arabic simple">
<li>The start offset of the match (a number)</li>
<li>The end offset of the match (a number)</li>
<li><em>repl_out</em></li>
</ol>
</blockquote>
<p>The type of its first return controls the replacement produced by gsub for
the current match:</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">true</span></tt> -- replace/don't replace, according to <em>repl_out</em>;</li>
<li><tt class="docutils literal"><span class="pre">nil</span></tt>/<tt class="docutils literal"><span class="pre">false</span></tt> -- don't replace;</li>
<li>a string (or a number coerced to a string) -- replace by that string;</li>
</ul>
</blockquote>
<p>The type of its second return controls gsub behavior after the current
match is handled:</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">nil</span></tt>/<tt class="docutils literal"><span class="pre">false</span></tt> -- no changes: <em>n</em> will be called on the next match;</li>
<li><tt class="docutils literal"><span class="pre">true</span></tt> -- search for an unlimited number of matches; <em>n</em> will not be
called again;</li>
<li>a number -- maximum number of matches to search for, beginning from the
next match; <em>n</em> will not be called again;</li>
</ul>
</blockquote>
</li>
</ol>
</blockquote>
</div>
<hr class="docutils" />
<div class="section">
<h3><a class="toc-backref" href="#id8" id="split" name="split">split</a></h3>
<p><tt class="funcdef docutils literal"><span class="pre">rex.split</span> <span class="pre">(subj,</span> <span class="pre">sep,</span> <span class="pre">[cf],</span> <span class="pre">[ef],</span> <span class="pre">[lo])</span></tt></p>
<p>The function is intended for use in the <em>generic for</em> Lua construct.
It is used for splitting a subject string <em>subj</em> into parts (<em>sections</em>).
The <em>sep</em> parameter is a regular expression pattern representing
<strong>separators</strong> between the sections.</p>
<p>The function returns an iterator for repeated matching of the pattern <em>sep</em> in
the string <em>subj</em>, subject to flags <em>cf</em> and <em>ef</em>.</p>
<p>PCRE: A locale <em>lo</em> may be specified.</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="15%" />
<col width="51%" />
<col width="13%" />
<col width="21%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Parameter</th>
<th class="head">Description</th>
<th class="head">Type</th>
<th class="head">Default Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>subj</td>
<td>subject</td>
<td>string</td>
<td>n/a</td>
</tr>
<tr><td>sep</td>
<td>separator (regular expression
pattern)</td>
<td>string</td>
<td>n/a</td>
</tr>
<tr><td>[cf]</td>
<td>compilation flags (bitwise OR)</td>
<td>number</td>
<td><a class="reference" href="#cf">cf</a></td>
</tr>
<tr><td>[ef]</td>
<td>execution flags (bitwise OR)</td>
<td>number</td>
<td><a class="reference" href="#ef">ef</a></td>
</tr>
<tr><td>[lo]</td>
<td>[PCRE] locale</td>
<td>string
or
userdata</td>
<td><a class="reference" href="#locale">locale</a></td>
</tr>
</tbody>
</table>
</blockquote>
<p><strong>On every iteration pass, the iterator returns:</strong></p>
<blockquote>
<ol class="arabic simple">
<li>A subject section (can be an empty string), followed by</li>
<li>All captures in the order they appear in the <em>sep</em> pattern (or the entire
match if the <em>sep</em> pattern specified no captures). If there is no match
(this can occur only in the last iteration), then nothing is returned after
the subject section.</li>
</ol>
</blockquote>
<p>The iteration will continue till the end of the subject. Unlike <a class="reference" href="#gmatch">gmatch</a>, there
will always be at least one iteration pass, even if there's no matches in the
subject.</p>
</div>
<hr class="docutils" />
<div class="section">
<h3><a class="toc-backref" href="#id9" id="flags" name="flags">flags</a></h3>
<p><tt class="funcdef docutils literal"><span class="pre">rex.flags</span> <span class="pre">([tb])</span></tt></p>
<p>This function returns a table containing numeric values of the constants defined
by the used regex library (either PCRE or POSIX). Those constants are keyed by
their names (strings). If the table argument <em>tb</em> is supplied then it is used as
the output table, else a new table is created.</p>
<p>The constants contained in the returned table can then be used in most functions
and methods where <em>compilation flags</em> or <em>execution flags</em> can be specified.
They can also be used for comparing with return codes of some functions and
methods for determining the reason of failure. For details, see <a class="reference" href="http://www.pcre.org/pcre.txt">PCRE</a> and <a class="reference" href="http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html">POSIX</a>
documentation.</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="15%" />
<col width="52%" />
<col width="13%" />
<col width="21%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Parameter</th>
<th class="head">Description</th>
<th class="head">Type</th>
<th class="head">Default Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>[tb]</td>
<td>a table for placing results into</td>
<td>table</td>
<td><tt class="docutils literal"><span class="pre">nil</span></tt></td>
</tr>
</tbody>
</table>
</blockquote>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd><ol class="first last arabic simple">
<li>A table filled with the results.</li>
</ol>
</dd>
</dl>
</div>
<hr class="docutils" />
<div class="section">
<h3><a class="toc-backref" href="#id10" id="new" name="new">new</a></h3>
<p><tt class="funcdef docutils literal"><span class="pre">rex.new</span> <span class="pre">(patt,</span> <span class="pre">[cf],</span> <span class="pre">[lo])</span></tt></p>
<p>The functions compiles regular expression <em>patt</em> into a regular expression
object whose internal representation is correspondent to the library used (PCRE
or POSIX regex).  The returned result then can be used by the methods <a class="reference" href="#tfind">tfind</a>,
<a class="reference" href="#exec">exec</a> and <a class="reference" href="#dfa-exec">dfa_exec</a>.  Regular expression objects are automatically garbage
collected.</p>
<p>PCRE: A locale <em>lo</em> may be specified.</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="15%" />
<col width="51%" />
<col width="13%" />
<col width="21%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Parameter</th>
<th class="head">Description</th>
<th class="head">Type</th>
<th class="head">Default Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>patt</td>
<td>regular expression pattern</td>
<td>string</td>
<td>n/a</td>
</tr>
<tr><td>[cf]</td>
<td>compilation flags (bitwise OR)</td>
<td>number</td>
<td><a class="reference" href="#cf">cf</a></td>
</tr>
<tr><td>[lo]</td>
<td>[PCRE] locale</td>
<td>string
or
userdata</td>
<td><a class="reference" href="#locale">locale</a></td>
</tr>
</tbody>
</table>
</blockquote>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd><ol class="first last arabic simple">
<li>Compiled regular expression (a userdata).</li>
</ol>
</dd>
</dl>
</div>
<hr class="docutils" />
<div class="section">
<h3><a class="toc-backref" href="#id11" id="tfind" name="tfind">tfind</a></h3>
<p><tt class="funcdef docutils literal"><span class="pre">r:tfind</span> <span class="pre">(subj,</span> <span class="pre">[init],</span> <span class="pre">[ef])</span></tt></p>
<p>The method searches for the first match of the compiled regexp <em>r</em> in the
string <em>subj</em>, starting from offset <em>init</em>, subject to execution flags <em>ef</em>.</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="14%" />
<col width="54%" />
<col width="12%" />
<col width="20%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Parameter</th>
<th class="head">Description</th>
<th class="head">Type</th>
<th class="head">Default Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>r</td>
<td>regex object produced by <a class="reference" href="#new">new</a></td>
<td>userdata</td>
<td>n/a</td>
</tr>
<tr><td>subj</td>
<td>subject</td>
<td>string</td>
<td>n/a</td>
</tr>
<tr><td>[init]</td>
<td>start offset in the subject
(can be negative)</td>
<td>number</td>
<td>1</td>
</tr>
<tr><td>[ef]</td>
<td>execution flags (bitwise OR)</td>
<td>number</td>
<td><a class="reference" href="#ef">ef</a></td>
</tr>
</tbody>
</table>
</blockquote>
<dl class="docutils">
<dt><strong>Returns on success:</strong></dt>
<dd><ol class="first last arabic simple">
<li>The start point of the match (a number).</li>
<li>The end point of the match (a number).</li>
<li>Substring matches (&quot;captures&quot; in Lua terminology) are returned as a third
result, in a table. This table contains <tt class="docutils literal"><span class="pre">false</span></tt> in the positions where the
corresponding sub-pattern did not participate in the match.<ol class="arabic">
<li>PCRE: if <em>named subpatterns</em> are used then the table also contains
substring matches keyed by their correspondent subpattern names
(strings).</li>
</ol>
</li>
</ol>
</dd>
<dt><strong>Returns on failure:</strong></dt>
<dd><ol class="first last arabic simple">
<li><tt class="docutils literal"><span class="pre">nil</span></tt></li>
</ol>
</dd>
<dt><strong>Notes:</strong></dt>
<dd><ol class="first last arabic simple">
<li>If <em>named subpatterns</em> (see <a class="reference" href="http://www.pcre.org/pcre.txt">PCRE</a> docs) are used then the returned table
also contains substring matches keyed by their correspondent subpattern
names (strings).</li>
</ol>
</dd>
</dl>
</div>
<hr class="docutils" />
<div class="section">
<h3><a class="toc-backref" href="#id12" id="exec" name="exec">exec</a></h3>
<p><tt class="funcdef docutils literal"><span class="pre">r:exec</span> <span class="pre">(subj,</span> <span class="pre">[init],</span> <span class="pre">[ef])</span></tt></p>
<p>The method searches for the first match of the compiled regexp <em>r</em> in the
string <em>subj</em>, starting from offset <em>init</em>, subject to execution flags <em>ef</em>.</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="14%" />
<col width="54%" />
<col width="12%" />
<col width="20%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Parameter</th>
<th class="head">Description</th>
<th class="head">Type</th>
<th class="head">Default Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>r</td>
<td>regex object produced by <a class="reference" href="#new">new</a></td>
<td>userdata</td>
<td>n/a</td>
</tr>
<tr><td>subj</td>
<td>subject</td>
<td>string</td>
<td>n/a</td>
</tr>
<tr><td>[init]</td>
<td>start offset in the subject
(can be negative)</td>
<td>number</td>
<td>1</td>
</tr>
<tr><td>[ef]</td>
<td>execution flags (bitwise OR)</td>
<td>number</td>
<td><a class="reference" href="#ef">ef</a></td>
</tr>
</tbody>
</table>
</blockquote>
<dl class="docutils">
<dt><strong>Returns on success:</strong></dt>
<dd><ol class="first last arabic simple">
<li>The start point of the first match (a number).</li>
<li>The end point of the first match (a number).</li>
<li>The offsets of substring matches (&quot;captures&quot; in Lua terminology) are
returned as a third result, in a table. This table contains <tt class="docutils literal"><span class="pre">false</span></tt> in the
positions where the corresponding sub-pattern did not participate in the
match.<ol class="arabic">
<li>PCRE: if <em>named subpatterns</em> are used then the table also contains
substring matches keyed by their correspondent subpattern names
(strings).</li>
</ol>
</li>
</ol>
</dd>
<dt><strong>Returns on failure:</strong></dt>
<dd><ol class="first last arabic simple">
<li><tt class="docutils literal"><span class="pre">nil</span></tt></li>
</ol>
</dd>
<dt><strong>Example:</strong></dt>
<dd>If the whole match is at offsets 10,20 and substring matches are at offsets
12,14 and 16,19 then the function returns the following: 10, 20,
{ 12,14,16,19 }.</dd>
</dl>
</div>
</div>
<hr class="docutils" />
<div class="section">
<h2><a class="toc-backref" href="#id13" id="pcre-only-functions-and-methods" name="pcre-only-functions-and-methods">PCRE-only functions and methods</a></h2>
<div class="section">
<h3><a class="toc-backref" href="#id14" id="dfa-exec" name="dfa-exec">dfa_exec</a></h3>
<p>[PCRE 6.0 and later. See <em>pcre_dfa_exec</em> in the <a class="reference" href="http://www.pcre.org/pcre.txt">PCRE</a> docs.]</p>
<p><tt class="funcdef docutils literal"><span class="pre">r:dfa_exec</span> <span class="pre">(subj,</span> <span class="pre">[init],</span> <span class="pre">[ef],</span> <span class="pre">[ovecsize],</span> <span class="pre">[wscount])</span></tt></p>
<p>The method matches a compiled regular expression <em>r</em> against a given subject
string <em>subj</em>, using a DFA matching algorithm.</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="15%" />
<col width="54%" />
<col width="12%" />
<col width="19%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Parameter</th>
<th class="head">Description</th>
<th class="head">Type</th>
<th class="head">Default Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>r</td>
<td>regex object produced by <a class="reference" href="#new">new</a></td>
<td>userdata</td>
<td>n/a</td>
</tr>
<tr><td>subj</td>
<td>subject</td>
<td>string</td>
<td>n/a</td>
</tr>
<tr><td>[init]</td>
<td>start offset in the subject
(can be negative)</td>
<td>number</td>
<td>1</td>
</tr>
<tr><td>[ef]</td>
<td>execution flags (bitwise OR)</td>
<td>number</td>
<td><a class="reference" href="#ef">ef</a></td>
</tr>
<tr><td>[ovecsize]</td>
<td>size of the array for result offsets</td>
<td>number</td>
<td>100</td>
</tr>
<tr><td>[wscount]</td>
<td>number of elements in the working
space array</td>
<td>number</td>
<td>50</td>
</tr>
</tbody>
</table>
</blockquote>
<dl class="docutils">
<dt><strong>Returns on success (either full or partial match):</strong></dt>
<dd><ol class="first last arabic simple">
<li>The start point of the matches found (a number).</li>
<li>A table containing the end points of the matches found, the longer matches
first.</li>
<li>The return value of the underlying <em>pcre_dfa_exec</em> call (a number).</li>
</ol>
</dd>
<dt><strong>Returns on failure (no match):</strong></dt>
<dd><ol class="first last arabic simple">
<li><tt class="docutils literal"><span class="pre">nil</span></tt></li>
</ol>
</dd>
<dt><strong>Example:</strong></dt>
<dd>If there are 3 matches found starting at offset 10 and ending at offsets 15, 20
and 25 then the function returns the following: 10, { 25,20,15 }, 3.</dd>
</dl>
</div>
<hr class="docutils" />
<div class="section">
<h3><a class="toc-backref" href="#id15" id="maketables" name="maketables">maketables</a></h3>
<p>[PCRE only. See <em>pcre_maketables</em> in the <a class="reference" href="http://www.pcre.org/pcre.txt">PCRE</a> docs.]</p>
<p><tt class="funcdef docutils literal"><span class="pre">rex.maketables</span> <span class="pre">()</span></tt></p>
<p>Creates a set of character tables corresponding to the current locale and
returns it as a userdata. The returned value can be passed to any Lrexlib
function accepting the <em>locale</em> parameter.</p>
</div>
<hr class="docutils" />
<div class="section">
<h3><a class="toc-backref" href="#id16" id="config" name="config">config</a></h3>
<p>[PCRE 4.0 and later. See <em>pcre_config</em> in the <a class="reference" href="http://www.pcre.org/pcre.txt">PCRE</a> docs.]</p>
<p><tt class="funcdef docutils literal"><span class="pre">rex.config</span> <span class="pre">([tb])</span></tt></p>
<p>This function returns a table containing the values of the configuration
parameters used at PCRE library build-time. Those parameters (numbers) are
keyed by their names (strings). If the table argument <em>tb</em> is supplied then it
is used as the output table, else a new table is created.</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="15%" />
<col width="52%" />
<col width="13%" />
<col width="21%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Parameter</th>
<th class="head">Description</th>
<th class="head">Type</th>
<th class="head">Default Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>[tb]</td>
<td>a table for placing results into</td>
<td>table</td>
<td><tt class="docutils literal"><span class="pre">nil</span></tt></td>
</tr>
</tbody>
</table>
</blockquote>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd><ol class="first last arabic simple">
<li>A table filled with the results.</li>
</ol>
</dd>
</dl>
</div>
<hr class="docutils" />
<div class="section">
<h3><a class="toc-backref" href="#id17" id="version" name="version">version</a></h3>
<p>[PCRE only. See <em>pcre_version</em> in the <a class="reference" href="http://www.pcre.org/pcre.txt">PCRE</a> docs.]</p>
<p><tt class="funcdef docutils literal"><span class="pre">rex.version</span> <span class="pre">()</span></tt></p>
<p>This function returns a string containing the version of the used PCRE library
and its release date.</p>
</div>
</div>
<hr class="docutils" />
<div class="section">
<h2><a class="toc-backref" href="#id18" id="other-functions" name="other-functions">Other functions</a></h2>
<div class="section">
<h3><a class="toc-backref" href="#id19" id="plainfind" name="plainfind">plainfind</a></h3>
<p><tt class="funcdef docutils literal"><span class="pre">rex.plainfind</span> <span class="pre">(subj,</span> <span class="pre">patt,</span> <span class="pre">[init],</span> <span class="pre">[ci])</span></tt></p>
<p>The function searches for the first match of the string <em>patt</em> in the subject
<em>subj</em>, starting from offset <em>init</em>.</p>
<blockquote>
<ul class="simple">
<li>The string <em>patt</em> is not regular expression, all its characters stand for
themselves.</li>
<li>Both strings <em>subj</em> and <em>patt</em> can have embedded zeros.</li>
<li>The flag <em>ci</em> specifies case-insensitive search (current locale is used).</li>
<li>This function uses neither PCRE nor POSIX regex library.</li>
</ul>
<table border="1" class="docutils">
<colgroup>
<col width="16%" />
<col width="47%" />
<col width="14%" />
<col width="23%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Parameter</th>
<th class="head">Description</th>
<th class="head">Type</th>
<th class="head">Default Value</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>subj</td>
<td>subject</td>
<td>string</td>
<td>n/a</td>
</tr>
<tr><td>patt</td>
<td>text to find</td>
<td>string</td>
<td>n/a</td>
</tr>
<tr><td>[init]</td>
<td>start offset in the subject
(can be negative)</td>
<td>number</td>
<td>1</td>
</tr>
<tr><td>[ci]</td>
<td>case insensitive search</td>
<td>boolean</td>
<td><tt class="docutils literal"><span class="pre">false</span></tt></td>
</tr>
</tbody>
</table>
</blockquote>
<dl class="docutils">
<dt><strong>Returns on success:</strong></dt>
<dd><ol class="first last arabic simple">
<li>The start point of the match (a number).</li>
<li>The end point of the match (a number).</li>
</ol>
</dd>
<dt><strong>Returns on failure:</strong></dt>
<dd><ol class="first last arabic simple">
<li><tt class="docutils literal"><span class="pre">nil</span></tt></li>
</ol>
</dd>
</dl>
</div>
</div>
<hr class="docutils" />
<div class="section">
<h2><a class="toc-backref" href="#id20" id="incompatibilities-with-the-previous-versions" name="incompatibilities-with-the-previous-versions">Incompatibilities with the Previous Versions</a></h2>
<p><strong>Incompatibilities between the versions 2.0 and 1.19:</strong></p>
<blockquote>
<ol class="arabic simple">
<li>Lua 5.1 is required</li>
<li>Functions <tt class="docutils literal"><span class="pre">newPCRE</span></tt> and <tt class="docutils literal"><span class="pre">newPOSIX</span></tt> renamed to <a class="reference" href="#new">new</a></li>
<li>Functions <tt class="docutils literal"><span class="pre">flagsPCRE</span></tt> and <tt class="docutils literal"><span class="pre">flagsPOSIX</span></tt> renamed to <a class="reference" href="#flags">flags</a></li>
<li>Function <tt class="docutils literal"><span class="pre">versionPCRE</span></tt> renamed to <a class="reference" href="#version">version</a></li>
<li>Method <tt class="docutils literal"><span class="pre">match</span></tt> renamed to <a class="reference" href="#tfind">tfind</a></li>
<li>Method <tt class="docutils literal"><span class="pre">gmatch</span></tt> removed (similar functionality is provided by function
<a class="reference" href="#gmatch">gmatch</a>)</li>
<li>Methods <a class="reference" href="#tfind">tfind</a> and <a class="reference" href="#exec">exec</a>: 2 values are returned on failure</li>
<li>(PCRE) <a class="reference" href="#exec">exec</a>: the returned table may additionally contain <em>named
subpatterns</em></li>
</ol>
</blockquote>
<p><strong>Incompatibilities between the versions 2.1 and 2.0:</strong></p>
<blockquote>
<ol class="arabic simple">
<li><a class="reference" href="#match">match</a>, <a class="reference" href="#find">find</a>, <a class="reference" href="#tfind">tfind</a>, <a class="reference" href="#exec">exec</a>, <a class="reference" href="#dfa-exec">dfa_exec</a>: only one value (a <tt class="docutils literal"><span class="pre">nil</span></tt>) is
returned when the subject does not match the pattern. Any other failure
generates an error.</li>
</ol>
</blockquote>
<p><strong>Incompatibilities between the versions 2.2 and 2.1:</strong></p>
<blockquote>
<ol class="arabic simple">
<li><a class="reference" href="#gsub">gsub</a>: a special &quot;break&quot; return of <em>repl</em> function is deprecated.</li>
<li>(PCRE) <a class="reference" href="#gsub">gsub</a>, <a class="reference" href="#gmatch">gmatch</a>: after finding an empty match at the current
position, the functions try to find a non-empty match anchored to the same
position.</li>
</ol>
</blockquote>
</div>
</div>
<div class="footer">
<hr class="footer" />
Generated on: 2007-06-18 17:22 UTC.

</div>
</body>
</html>
